New chapter with a "Migration Checklist" of things people need to do to be

2004-01-22  Federico Mena Quintero  <federico@ximian.com>

	* gtk/migrating-checklist.sgml: New chapter with a "Migration
	Checklist" of things people need to do to be good citizens in the
	GTK+ world.  This is mainly a way to tell people about interesting
	APIs that they should use instead of hand-hacked approaches.

	* gtk/gtk-docs.sgml: Added migrating-checklist.sgml.

	* gtk/Makefile.am (content_files): Likewise.

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index 8488675ac8a9237b18cfd633db06f1c1dd0d98f1..21e71de682e2d21b99a1cd1a3c59158e8d6a5616 100644 (file)
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,14 @@
+2004-01-22  Federico Mena Quintero  <federico@ximian.com>
+
+       * gtk/migrating-checklist.sgml: New chapter with a "Migration
+       Checklist" of things people need to do to be good citizens in the
+       GTK+ world.  This is mainly a way to tell people about interesting
+       APIs that they should use instead of hand-hacked approaches.
+
+       * gtk/gtk-docs.sgml: Added migrating-checklist.sgml.
+
+       * gtk/Makefile.am (content_files): Likewise.
+
 Thu Jan 22 01:46:45 2004  Jonathan Blandford  <jrb@gnome.org>
 
        * gtk/tmpl/gtktreemodelsort.sgml: new introduction section.

diff --git a/docs/reference/gtk/Makefile.am b/docs/reference/gtk/Makefile.am
index 0c7534d97c1b6acddc5a54f54d09f13152dd76bf..a40008fa1a91f95f8e66222cda8b54bbaedae4d3 100644 (file)
--- a/docs/reference/gtk/Makefile.am
+++ b/docs/reference/gtk/Makefile.am
@@ -87,6 +87,7 @@ content_files =                                       \
        changes-2.0.sgml                        \
        compiling.sgml                          \
        framebuffer.sgml                        \
+       migrating-checklist.sgml                \
        migrating-GtkAction.sgml                \
        migrating-GtkFileChooser.sgml           \
        objects_grouped.sgml                    \

diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml
index 2632b9057d654120dcd177786c57676bdee02193..5c14e72d6254b4f7b236148f90bc360b7e6e5e3a 100644 (file)
--- a/docs/reference/gtk/gtk-docs.sgml
+++ b/docs/reference/gtk/gtk-docs.sgml
@@ -179,6 +179,7 @@
 <!ENTITY gtk-Questions SYSTEM "question_index.sgml">
 <!ENTITY gtk-Changes-1-2 SYSTEM "changes-1.2.sgml">
 <!ENTITY gtk-Changes-2-0 SYSTEM "changes-2.0.sgml">
+<!ENTITY gtk-migrating-checklist SYSTEM "migrating-checklist.sgml">
 <!ENTITY gtk-migrating-GtkFileChooser SYSTEM "migrating-GtkFileChooser.sgml">
 <!ENTITY gtk-migrating-GtkAction SYSTEM "migrating-GtkAction.sgml">
 <!ENTITY version SYSTEM "version.xml">
@@ -541,6 +542,7 @@ that is, GUI components such as <link linkend="GtkButton">GtkButton</link> or
       </para>
     </partintro>
 
+    &gtk-migrating-checklist;
     &gtk-Changes-1-2;
     &gtk-Changes-2-0;
     &gtk-migrating-GtkFileChooser;

diff --git a/docs/reference/gtk/migrating-checklist.sgml b/docs/reference/gtk/migrating-checklist.sgml
new file mode 100644 (file)
index 0000000..51a1e9b
--- /dev/null
+++ b/docs/reference/gtk/migrating-checklist.sgml
@@ -0,0 +1,141 @@
+<chapter id="gtk-migrating-checklist">
+  <title>Migration Checklist</title>
+
+  <para>
+    This chapter includes a checklist of things you need to do to
+    ensure that your programs are good citizens in the GTK+ world.  By
+    paying attention to the points in the checklist, you ensure that
+    many automatic features of GTK+ will work correctly in your
+    program.
+  </para>
+
+  <section id="checklist-popup-menu">
+    <title>Implement GtkWidget::popup_menu</title>
+
+    <formalpara>
+      <title>Why</title>
+      <para>
+       By handling this signal, you let widgets have
+       context-sensitive menus that can be invoked with the standard
+       key bindings.
+      </para>
+    </formalpara>
+
+    <para>
+      The <link
+      linkend="GtkWidget-popup-menu">GtkWidget::popup_menu</link>
+      signal instructs the widget for which it is emitted to create a
+      context-sensitive popup menu.  By default, the <link
+      linkend="gtk-bindings">key binding mechanism</link> is set to
+      emit this signal when the
+      <keycombo><keycap>Shift</keycap><keycap>F10</keycap></keycombo>
+      or <keycap>Menu</keycap> keys are pressed while a widget has the
+      focus.  If a widget in your application shows a popup menu when
+      you press a mouse button, you can make it work as well through
+      the normal key binding mechanism in the following fahion:
+    </para>
+
+    <orderedlist>
+      <listitem>
+       <para>
+         Write a function to create and show a popup menu.  This
+         function needs to know the button number and the event's
+         time to pass them to gtk_menu_popup().  You can implement
+         such a function like this:
+       </para>
+
+       <programlisting id="do_popup_menu">
+static void
+do_popup_menu (GtkWidget *my_widget, GdkEventButton *event)
+{
+  GtkWidget *menu;
+  int button, event_time;
+
+  menu = gtk_menu_new ();
+  g_signal_connect (menu, "deactivate", 
+                    G_CALLBACK (gtk_widget_destroy), NULL);
+
+  /* ... add menu items ... */
+
+  if (event)
+    {
+      button = event->button;
+      event_time = event->time;
+    }
+  else
+    {
+      button = 0;
+      event_time = gtk_get_current_event_time ();
+    }
+
+  gtk_menu_popup (GTK_MENU (popup), NULL, NULL, NULL, NULL, 
+                  button, event_time);
+}
+       </programlisting>
+      </listitem>
+
+      <listitem>
+       <para>
+         In your button_press handler, call this function when you
+         need to pop up a menu:
+       </para>
+
+       <programlisting>
+static gboolean
+my_widget_button_press_event_handler (GtkWidget *widget, GdkEventButton *event)
+{
+  /* Ignore double-clicks and triple-clicks */
+  if (event->button == 3 &amp;&amp; event->type == GDK_BUTTON_PRESS)
+    {
+      do_popup_menu (widget, event);
+      return TRUE;
+    }
+
+  return FALSE;
+}
+       </programlisting>
+      </listitem>
+
+      <listitem>
+       <para>
+         Implement a handler for the popup_menu signal:
+       </para>
+
+       <programlisting>
+static gboolean
+my_widget_popup_menu_handler (GtkWidget *widget)
+{
+  do_popup_menu (widget, NULL);
+  return TRUE;
+}
+       </programlisting>
+      </listitem>
+    </orderedlist>
+
+    <note>
+      <para>
+       If you do not pass a positioning function to gtk_menu_popup(),
+       it will show the menu at the mouse position by default.  This
+       is what you usually want when the menu is shown as a result of
+       pressing a mouse button.  However, if you press the
+       <keycombo><keycap>Shift</keycap><keycap>F10</keycap></keycombo>
+       or <keycap>Menu</keycap> keys while the widget is focused, the
+       mouse cursor may not be near the widget at all.  In the <link
+       linkend="do_popup_menu">example above</link>, you may want to
+       provide your own <link
+       linkend="GtkMenuPositionFunc">menu-positioning function</link>
+       in the case where the <parameter>event</parameter> is
+       <constant>NULL</constant>.  This function should compute the
+       desired position for a menu when it is invoked through the
+       keyboard.
+      </para>
+    </note>
+  </section>
+</chapter>
+
+<!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("gtk-docs.sgml" "book" "part" "chapter")
+End:
+-->